<!DOCTYPE HTML>
<html lang="en">
<head>

<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >

   <meta charset="utf-8">
  <link REL="STYLESHEET" HREF="../../book.css" TYPE="text/css">
  <title>Project description file</title>
</head>
<body>

<h1>
The Project Description File</h1>
<b><i>Description:</i></b> When a project is created in the workspace,
a project description file is automatically generated that describes the
project.&nbsp; The purpose of this file is to make the project self-describing,
so that a project that is zipped up or released to a server can be correctly
recreated in another workspace.&nbsp; This file is always called ".project",
and is located as a direct member of the project's content area.&nbsp;
The name of the file is exposed through the static field <code>DESCRIPTION_FILE_NAME</code>
on <code>org.eclipse.core.resources.IProjectDescription.</code>

<p>The name, location, and content of this file are part of the workspace
API.&nbsp; This means they are guaranteed not to change in a way that would
break existing users of the file.&nbsp; However, the right to add additional
elements and attributes to the markup is reserved for possible future additions
to the file.&nbsp; For this reason, clients that read the description file
contents should tolerate unknown elements and attributes.
</p>

<p>Clients that modify, delete, or replace the project description file
do so at their own risk.&nbsp; Projects with invalid or missing description
files will not be generally usable.&nbsp; If a project with an invalid
description file is discovered on workspace startup, the project is closed,
and it will not be possible to open it until the project description file
has been repaired.&nbsp; The workspace will not generally attempt to automatically
repair a missing or invalid description file.&nbsp; One exception is that
missing project description files will be regenerated during workspace
save and on calls to <code>IProject.setDescription</code>.
</p>

<p>Modifications to the project description file have mostly the same effect
as changing the project description via <code>IProject.setDescription</code>.&nbsp;
One exception is that adding or removing project natures will not trigger
the corresponding nature's configure or deconfigure method.&nbsp; Another
exception is that changes to the project name are ignored.
</p>

<p>If a new project is created at a location that contains an existing
project description file, the contents of that description file will be
honoured as the project description.&nbsp; One exception is that the project
name in the file will be ignored if it does not match the name of the project
being created.&nbsp; If the description file on disk is invalid, the project
creation will fail.
</p>

<br>&nbsp;
<p><b><i>Configuration Markup:</i></b></p>
<p><code>&nbsp;&nbsp; &lt;!ELEMENT projectDescription (name, comment, projects,
buildSpec, natures, linkedResources)&gt;</code></p>
<p><code>&nbsp;&nbsp; &lt;!ELEMENT name EMPTY&gt;</code></p>
<ul>
<li>
<b>name </b>- the name of the project.&nbsp; Ignored if it does match the
name of the project using this description.&nbsp; Corresponds to <code>IProjectDescription.getName()</code>.</li>
</ul>
<p><code>&nbsp;&nbsp; &lt;!ELEMENT comment EMPTY&gt;</code></p>
<ul>
<li>
<b>comment</b> - a comment for the project.&nbsp; The comment can have
arbitrary contents that are not interpreted by the project or workspace.&nbsp;
Corresponds to <code>IProjectDescription.getComment()</code>.</li>
</ul>
<code>&nbsp;&nbsp; &lt;!ELEMENT projects (project)*&gt;</code>
<br><code>&nbsp;&nbsp; &lt;!ELEMENT project EMPTY&gt;</code>
<ul>
<li>
<b>projects</b> - the names of the projects that are referenced by this
project.&nbsp; Corresponds to <code>IProjectDescription.getReferencedProjects().</code></li>
</ul>
<p><code>&nbsp;&nbsp; &lt;!ELEMENT buildSpec (buildCommand)*&gt;</code></p>
<p><code>&nbsp;&nbsp; &lt;!ELEMENT buildCommand (name, arguments)&gt;</code> </p>
<p><code>&nbsp;&nbsp; &lt;!ELEMENT name EMPTY&gt;</code> </p>
<p><code>&nbsp;&nbsp; &lt;!ELEMENT arguments (dictionary?)&gt;</code></p>
<p><code>&nbsp;&nbsp; &lt;!ELEMENT dictionary (key, value)*&gt;</code></p>
<p><code>&nbsp;&nbsp; &lt;!ELEMENT key EMPTY&gt;</code></p>
<p><code>&nbsp;&nbsp; &lt;!ELEMENT value EMPTY&gt;</code></p>
<ul>
<li><b>buildSpec</b> - the ordered list of build commands for this project.&nbsp;
Corresponds to <code>IProjectDescription.getBuildSpec().</code></li>
<li><b>buildCommand </b>- a single build commands for this project.&nbsp; Corresponds
to <code>org.eclipse.core.resources.ICommand.</code></li>
<li><b>name</b> - the symbolic name of an incremental project builder.&nbsp;
Corresponds to <code>ICommand.getBuilderName().</code></li>
<li><b>arguments</b> - optional arguments that may be passed to the project
builder.&nbsp; Corresponds to <code>ICommand.getArguments()</code>.</li>
<li><b>dictionary</b> - a list of &lt;key, value&gt; pairs in the argument list.&nbsp;
Analagous to <code>java.util.Map.</code></li>
</ul>
<p><code>&nbsp;&nbsp; &lt;!ELEMENT natures (nature)*&gt;</code></p>
<p><code>&nbsp;&nbsp; &lt;!ELEMENT nature EMPTY&gt;</code></p>
<ul>
<li>
<b>natures </b>- the names of the natures that are on this project.&nbsp;
Corresponds to <code>IProjectDescription.getNatureIds().</code></li>
<li><b>nature </b>- the name of a single natures on this project.</li>
</ul>
<p><code>&nbsp;&nbsp; &lt;!ELEMENT linkedResources (link)*&gt;</code></p>
<p><code>&nbsp;&nbsp; &lt;!ELEMENT link (name, type, location)&gt;</code></p>
<p><code>&nbsp;&nbsp; &lt;!ELEMENT name EMPTY&gt;</code> </p>
<p><code>&nbsp;&nbsp; &lt;!ELEMENT type EMPTY&gt;</code> </p>
<p><code>&nbsp;&nbsp; &lt;!ELEMENT location EMPTY&gt;</code></p>

<ul>
<li><b>linkedResources</b> - the list of linked resources for this project.</li>
<li><b>link</b> - the definition of a single linked resource.</li>
<li><b>name</b> - the project-relative path of the linked resource as it appears in the workspace.</li>
<li><b>type</b> - the resource type.  Value values are: &quot;1&quot; for a file,
or &quot;2&quot; for a folder.</li>
<li><b>location</b> - the local file system path of the target of the linked resource.  Either an
absolute path, or a relative path whose first segment is the name of a workspace
path variable.</li>
<li><b>locationURI</b> - if the file is not in the local file system, this attribute
contains the absolute URI of the resource in some backing file system.
</li>
</ul>

<b><i>Examples: </i></b>The following is a sample project description file.&nbsp;
The project has a single nature and builder configured, and some project
references.
<p><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;</code>
<br><code>&lt;projectDescription&gt;</code>
<br><code>&nbsp;&nbsp;&nbsp; &lt;name&gt;WinterProject&lt;/name&gt;</code>
<br><code>&nbsp;&nbsp;&nbsp; &lt;comment&gt;This is a cool project.&lt;/comment&gt;</code>
<br><code>&nbsp;&nbsp;&nbsp; &lt;projects&gt;</code>
<br><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;project&gt;org.seasons.sdt&lt;/project&gt;</code>
<br><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;project&gt;CoolStuff&lt;/project&gt;</code>
<br><code>&nbsp;&nbsp;&nbsp; &lt;/projects&gt;</code>
<br><code>&nbsp;&nbsp;&nbsp; &lt;buildSpec&gt;</code>
<br><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;buildCommand&gt;</code>
<br><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;name&gt;org.seasons.sdt.seasonBuilder&lt;/name&gt;</code>
<br><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;arguments&gt;</code>
<br><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;dictionary&gt;</code>
<br><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;key&gt;climate&lt;/key&gt;</code>
<br><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;value&gt;cold&lt;/value&gt;</code>
<br><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;/dictionary&gt;</code>
<br><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;/arguments&gt;</code>
<br><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;/buildCommand&gt;</code>
<br><code>&nbsp;&nbsp;&nbsp; &lt;/buildSpec&gt;</code>
<br><code>&nbsp;&nbsp;&nbsp; &lt;natures&gt;</code>
<br><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;nature&gt;org.seasons.sdt.seasonNature&lt;/nature&gt;</code>
<br><code>&nbsp;&nbsp;&nbsp; &lt;/natures&gt;</code>
<br><code>&lt;/projectDescription&gt;</code>
<br></p>
<p><b><i>API Information:</i></b> The contents of the project description
file map to the <code>org.eclipse.core.resources.IProjectDescription</code>
interface. The project description file can be overwritten by the method
<code>IProject.setDescription()</code>.</p>
</body>
</html>
